feat: play Audius playlists in a Winamp player - #1490

Summary

The first step of a player-first plan for #1380, replacing #1476 (now playing from Last.fm), as agreed there. On a computer, members can search winamp (or webamp, or llama) to open a Winamp player that keeps playing while you move between pages, starting with six lo-fi tracks. Members can share a public Audius playlist or album in profile settings, and their profile gets a ♫ button that plays it in Winamp for whoever is looking.

Why Audius

Winamp draws its visualizer and runs its equalizer on the audio itself, so the browser has to be allowed to read the audio. Spotify, YouTube and Apple Music only play inside their own players, and Last.fm has no audio at all. Audius's API needs no key, and its track streams are plain MP3s that any site may read (Access-Control-Allow-Origin: *), so the visualizer and equalizer work.

Roadmap

1. This PR: the player, a default playlist, and profile playlists from Audius.
2. Skins: pick one from the Winamp Skin Museum or upload a .wsz, saved per member. Playing someone's playlist could open it in their skin.
3. Winamp's keyboard shortcuts.
4. More sources for player playlists (no radio stations).

Changes

• lib/winamp.ts loads Webamp on first open, renders it into a fixed layer on body outside React, so page visits never unmount it, and reuses the one player when reopened. Webamp gets zIndex: 40, so its menus open above it and below dialogs. If it fails to load, a toast says so and nothing is left behind.
• Search offers Open Winamp to signed-in members where (hover: hover) and (pointer: fine) matches, and only for the whole word (winamp, webamp or llama), so searching "web" or "win" still searches. The profile button is hidden by the same media query in CSS, so nothing moves when the page hydrates.
• users.playlist_url, hidden from public payloads and included in the export. PUT/DELETE settings/playlist shares and stops sharing a playlist. Saving checks the link with Audius, is blocked during a timeout, and is limited to 10 a minute. Both fire ProfilesUpdated and UsersUpdated.
• PlaylistProvider, with AudiusPlaylistProvider (one resolve call per playlist; rejects private playlists; leaves out tracks that are gated, deleted, or missing an id or title; keeps the first 200; uses the stable /v1/tracks/{id}/stream links, not the signed ones that expire) and NullPlaylistProvider for local and testing.
• The profile page gets a live hasPlaylist prop and an optional playlist prop, which the button loads with a partial reload the first time the pointer is on it or it has keyboard focus (again if it came back empty), together with the Webamp chunk. The click then creates Webamp and starts the playlist before it returns, so the browser counts it as the click that started the sound. Clicked before the playlist arrives, the button shows a spinner and starts it once it does. PlaylistQuery caches the tracks per link for 10 minutes (1 minute after a failure).
• Remove is optimistic, and the settings form keeps a line for its error so the buttons don't move.
• The privacy page names Audius among the third parties whose content you load, from when you open Winamp. KNOWLEDGE_BASE.md and PRODUCT.md describe the feature.

Data: users.playlist_url

• Why it's needed: the profile can't load a member's playlist without its link.
• Who sees it: only its owner, in settings and in their export. It's hidden from every payload; visitors only get the tracks Audius serves.
• When it's deleted: when the member presses Remove, or with their account.

Validation

Local, on c7fb97c9 (rebased onto 946d5743), on macOS with PHP 8.5, Postgres 17 and Node 24 (CI hasn't run yet):

• composer test:lint, composer test:types: pass.
• composer test:type-coverage: 100%.
• composer test:unit: 5,871 Pest tests pass at 100% coverage. 302 Node unit tests and 1,078 component tests pass.
• In Chrome against the real Audius API:
  • A Spotify link is rejected with "Use a link to a public playlist or album on Audius." A real playlist saves, and Remove clears it.
  • The ♫ button loaded all 126 tracks of a test playlist and played them (192 kbps). The visualizer draws, so the audio is readable.
  • The music kept playing after client-side navigation to another page.
  • Opening Winamp from search showed the six default tracks, stopped. Webamp loads the first one from Audius as it opens, so the privacy page says Audius is reached once you open Winamp. Its right-click menu opens above it.
  • Closing it and searching llama brought back the same single player.
  • Hovering ♫ fetched the playlist once and loaded Webamp. The click then created Webamp's audio and called play() inside the click. Clicking straight away showed the spinner, fetched once, and played when the playlist arrived.

Visual evidence

Chrome (2x), signed in, looking at a member who shares a playlist. Before is production (84c5496a, before #1489, which has no web UI), after is this branch, same local data. The player was playing a real Audius playlist (the local binding was switched to Audius for the captures only).

Profile header. The ♫ button appears for members who share a playlist, on computers only.

	Before	After
1440×900 light
1440×900 dark
390×844 light
390×844 dark

1366×650: light before · light after · dark before · dark after

Winamp playing the member's playlist after pressing ♫:

Light	Dark

1366×650: light · dark. Winamp's menu opens above it: light · dark. The ♫ button clicked before the playlist has loaded: light · dark.

Profile settings. The new Winamp playlist section, and the error for a link that isn't an Audius playlist.

	Before	After
1440×900 light
1440×900 dark
390×844 light
390×844 dark

1366×650: light before · light after · dark before · dark after

Rejected link (the buttons stay put): light · dark

Search for "winamp". Offers Open Winamp on computers; phones get nothing new.

	Before	After
1440×900 light
1440×900 dark
390×844 light

1366×650 and 390×844 dark: light before · light after · dark before · dark after · 390 dark before · 390 dark after

Layout shift (PerformanceObserver, layout-shift): the profile and settings pages measure the same on both branches, 0 at 390×844, 0.0017 at 1440×900 and 0.0026 at 1366×650 (the last two already on production). Opening Winamp and saving a link add 0, and a rejected link moves the Save button 0px.

Device verification

Safari 27.2 on macOS, driven through safaridriver with its normal autoplay rules (webkit:alwaysAllowAutoplay: false), with Webamp's output routed to a silent gain node so the browser's checks were unchanged: hovering ♫ and then clicking created Webamp's AudioContext and called play() inside the click, and it played. Clicking straight away also played when the playlist arrived within a second. With the playlist held back 6 seconds, the audio element played but the AudioContext stayed suspended, so there was no sound until Winamp's Play was pressed.

No hardware or simulator was available (no Xcode on this machine). 390×844 was checked with Chrome's mobile emulation (touch, mobile user agent): the ♫ button and the search action stay hidden, and the settings section's input uses 16px text, so iOS shouldn't zoom. Not checked: the on-screen keyboard and safe areas on a real phone.

Independent review

A separate, read-only reviewer agent was given the task, the repo guidelines, the full diff and these captures. Its first verdict was CODE: FAIL, because Winamp's menus opened under the player and searching "web" or "win" offered Winamp, plus smaller points. All of them are fixed above or listed under Limitations. A fresh review of 84c5496a..3311c698, media 1778724a, gave CODE: PASS and VISUAL: PASS. After rebasing onto 01c39a2a (#1489), the patch is unchanged except the migration's timestamp, which now sorts after #1489's. A fresh review of 01c39a2a..5dad2231 checked how it interacts with #1489 (hidden attributes, export, routes, limiters), and gave CODE: PASS and VISUAL: PASS, with the captures still applying. After CodeRabbit's review, the branch was rebased onto facb8046 (#1491), private playlists are rejected, and the privacy page and knowledge base say Audius is reached once Winamp opens. A fresh review of facb8046..5f482ac3 gave CODE: PASS and VISUAL: PASS, with the captures still applying. After CodeRabbit's note on blocked autoplay, the ♫ button starts playback inside the click. A review of that change gave CODE: PASS and VISUAL: FAIL, because the loading captures showed the old disabled button; they were retaken, the redundant showProgress option was dropped and two loader tests were added. The next review gave CODE: FAIL, because the failed-preload test never made the import fail; it now re-registers the mock, and fails if the retry is removed. A loaded playlist is no longer fetched again on every hover. The next review passed, noting that an empty result (such as after an Audius failure) would then stick for the visit; an empty result is now fetched again. A fresh review of facb8046..93bba2b7, media fd578701, gave CODE: PASS and VISUAL: PASS. After rebasing onto 096869fe (#1501), the patch is unchanged except the migration's timestamp, which now sorts after #1493's. A fresh review of 096869fe..ff54cf87 checked how it fits #1493, #1417, #1498, #1499 and #1501 (export, hidden attributes, routes, layout, knowledge base) and gave CODE: PASS and VISUAL: PASS, with the captures still applying. #1502 then landed, touching only apps/mobile and the linter's ignore list; after rebasing onto 30754428 the patch is identical, and a check of 30754428..428948c4 gave CODE: PASS and VISUAL: PASS. #1503 and #1505 then landed; after rebasing onto 946d5743 the patch is unchanged except the migration's timestamp, which now sorts after #1505's. A fresh review of 946d5743..c7fb97c9 checked how it fits them (export, shared props, last-seen tracking, layout, the lite mobile app, privacy page) and gave CODE: PASS and VISUAL: PASS, with the captures still applying.

Nits it left:

• The comment above the search keywords still describes prefix matching, which Winamp now skips. I left it unchanged, since this PR doesn't edit existing comments.
• If the Webamp constructor threw, an empty layer would stay behind.
• Remove drops keyboard focus to the page.

Limitations

• Audius's docs say its API is free and ask apps to credit artists; Winamp shows "artist – title" for every track. I couldn't read Audius's full API terms.
• Track titles in members' playlists aren't moderated. They only show inside Winamp after someone presses ♫.
• Opening Winamp loads its first track from Audius before play. Webamp has no public way to wait: appending the tracks instead of passing initialTracks leaves Play with nothing loaded, so it does nothing.
• The default playlist is six hard-coded Audius tracks. If an artist deletes one, that track won't play.
• The ♫ click starts playback itself once the playlist and the Webamp chunk have loaded (they load while the pointer is on the button). If someone clicks before that and they take longer than Safari's activation window (about 5 seconds), Webamp's AudioContext is created suspended and stays that way: Winamp shows the playlist as playing with no sound until the next click or key press on the page, such as Winamp's Play, which restarts the track with sound.
• Double-clicking ♫ while Winamp is still drawing for the first time restarts the first track.
• Once loaded, the playlist isn't fetched again during that profile visit, so a change the member makes while someone stays on their profile shows up after a page load.
• A timeout stops a member from changing their playlist, but doesn't remove one already shared.
• When nobody has played a playlist for 10 minutes and several people press play at once, each of them asks Audius once; there's no lock.
• A playlist Audius has but with nothing playable can still be saved; the ♫ button then says there's nothing to play.
• Webamp's own keyboard shortcuts are left off until the shortcuts step.
• Not checked in Firefox.

Summary by CodeRabbit

• New Features
  • Added a desktop Winamp player, accessible through search, with a built-in Audius lo-fi playlist.
  • Members can share a public Audius playlist or album from profile settings. Visitors can play shared tracks from the member’s profile.
  • Shared playlists load up to 200 playable tracks and refresh at most every ten minutes. Members can remove their shared playlist.
• Limitations
  • The player is available on desktop, not phones or tablets. Playback loads directly from Audius; Spotify, YouTube, and Apple Music links aren’t supported.